Skip to content

node: --decryptkey (and docker decrypt-key) turns a password-encrypted key into the plain key - #175

Merged
EnzinoBB merged 7 commits into
masterfrom
feat/decrypt-key
Nov 7, 2026
Merged

EnzinoBB merged 7 commits into
masterfrom
feat/decrypt-key

Conversation

@EnzinoBB

@EnzinoBB EnzinoBB commented Nov 7, 2026 •

Copy link
Copy Markdown
Collaborator

One command turns a node key encrypted with a password (--encryptkey, or the password choice at the first start) into the plain key file, after the old password is typed. It replaces the --dumpkeys + python + shred procedure.

Docker

docker compose stop
sudo cp old/NodePrivate.txt old/NodePublic.txt ~/.credits/keys/
sudo chown 1000:1000 ~/.credits/keys/NodePrivate.txt ~/.credits/keys/NodePublic.txt
docker compose run --rm node decrypt-key        # press p, then type the old password
docker compose up -d

Native (node stopped, in the csnode folder): ./node --decryptkey (Windows: node.exe --decryptkey)

What --decryptkey does

  • Uses the same key files as a start: --public-key-file and --private-key-file, by default NodePublic.txt and NodePrivate.txt.
  • Encrypted key: asks the password with the existing prompt (p/f, Enter password:) and asks again after a wrong one, as at a start. Then it:
    • checks that the key matches NodePublic.txt and refuses otherwise (also when the file is missing; that check runs before the password is asked);
    • keeps the encrypted original as NodePrivate.txt.encrypted-YYYYMMDD-HHMMSS, mode 0600. The file is created new and never overwrites anything; if the name is taken, -2, -3, ... is added;
    • writes the plain key atomically with the config: safer handling of the encrypted key file (atomic re-encryption, clear errors; format unchanged) #170 writer (tmp file, fsync, rename, 0600), in the plain format the node and keygen.py already write;
    • prints NodePrivate.txt is now in clear (address <base58 public key>); the encrypted original is kept as <file> and exits without starting the node.
  • Plain key: prints that it is already in clear, with the address, and exits 0.
  • Refuses with exit 3 when db/.lock is held (a running community node). It reads no config.ini and needs no network, database or executor. It runs right after --working_dir, before the configuration is read.
  • No new crypto: it uses cs::keyfile::decrypt from config: safer handling of the encrypted key file (atomic re-encryption, clear errors; format unchanged) #170. The secret buffers are zeroed. writeKeyFile moved to keyfilecrypt.cpp beside the new cs::keyfile::toPlain. The password loop of readKeys is now unlockWithPrompt, which both use, so a start behaves as before.

Docker

  • entrypoint.sh takes the command decrypt-key. It runs node --decryptkey on /data/keys with the terminal's input and exits, without writing a config or downloading anything. Any other command is refused with exit 2.
  • On a normal start, a keys/NodePrivate.txt that decodes to 88 bytes now stops the container (exit 3) with a message that points to docker compose run --rm node decrypt-key. Before, the node waited for a password that nobody could type.

Docs

Review fixes (76afbb6, 57e0dd1)

  • M1: the prompt now stops when stdin is at its end. Before, it looped forever. --decryptkey < /dev/null prints "Cancelled" and exits 1, and a start under systemd with an encrypted key exits.
  • M2: on Linux and macOS the password is read from std::cin, so a password piped with the choice now works: printf 'p\n%s\n' "$PW" | docker compose run --rm -T node decrypt-key.
    • On a terminal, echo and line editing are off for the whole read, and the prompt is printed only after that.
    • Windows keeps its console read, so it works in a console only. The docs say so.
  • L2: the .tmp file is created new with O_EXCL, after removing whatever had that name.
  • L5: when libsodium cannot allocate its memory, the node now says so (about 1 GB is needed) instead of "Incorrect password".
  • Docs: L1, L3, L5, L6, and a step that saves the generated keys in the Docker README.
  • Tests:
    • new unit tests: the end of input cancels; piped input opens the key.
    • manual runs: < /dev/null; piped input on the real community.17 image with the new binary; a pty session (no password echo); a low-memory run under ulimit -v.

Tests

  • Unit tests (KeyFileCryptToPlain.*, in the keyfilecrypt_tests ctest entry, whose filter is now KeyFileCrypt*):
    • an encrypted key gives back the original plain file byte for byte, and the backup is byte-identical with mode 0600;
    • a wrong password changes nothing;
    • a plain key is a no-op;
    • a mismatching or missing NodePublic.txt is refused;
    • a CRLF NodePublic.txt matches;
    • an existing backup name is never overwritten;
    • a missing or bad private key file is refused;
    • the timestamp has the right format.
  • packaging/docker/test/test-entrypoint.sh case 17:
    • an encrypted key stops a normal start with the message;
    • decrypt-key gets the right arguments and stdin;
    • a wrong password exits 1, and the right one writes the plain key without starting the node;
    • decrypt-key without keys, and an unknown command, are refused.
  • Manual run, on throwaway keys only:
    • Native: keys from keygen.py, encrypted by the node itself with --encryptkey, then --decryptkey with one wrong password and then the right one. The plain file is identical to the original, and the backup is identical to the encrypted file. A plain key, a held db/.lock (exit 3) and a mismatching public key (exit 1, nothing changed) all behave as described. It also ran in a folder with only the two key files.
    • Real image (community.17 package with this node binary) through docker compose run --rm node decrypt-key: the normal start refused, a wrong password and then the right one gave the original plain key.

🤖 Generated with Claude Code

EnzinoBB and others added 7 commits November 7, 2026 15:43
…cker or native)

A new section 10 for operators who keep an identity they already have: a
plain key in the native folder before the set-up, an encrypted key on a
console (not under systemd), a plain key in Docker (~/.credits/keys, uid
1000, mode 600; the container makes keys only when keys/NodePublic.txt is
missing), and an encrypted key in Docker, converted once with the image's
own node --dumpkeys. Also the native conversion for systemd. Troubleshooting
becomes section 11.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d key into the plain key

--decryptkey asks the password of the private key file the node encrypted (the same prompt and
retries as a start), checks that the key matches the public key file, keeps the encrypted file as
<private>.encrypted-YYYYMMDD-HHMMSS (mode 0600, created new, never overwriting), writes the plain
key in place with the atomic key-file writer of #170 and exits. A plain key is left as it is (exit
0). It reads no configuration and opens no network or database; it refuses while db/.lock is held.
The file format is the plain one the node already reads; no new crypto.

writeKeyFile moves to keyfilecrypt.cpp with the new cs::keyfile::toPlain; the password loop of
readKeys becomes unlockWithPrompt, shared by both.

Docker: `docker compose run --rm node decrypt-key` runs it on /data/keys; a normal start with an
encrypted key now stops with that command instead of waiting for a password. quick-start.md
section 10 and the Docker README use these steps instead of the --dumpkeys procedure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review of #175.

M1: usePassword() looped forever once stdin was at its end (cin >> choice failed and left the
choice empty). It now returns, and its callers stop: --decryptkey < /dev/null prints "Cancelled"
and exits 1, and a start with an encrypted key and no input (systemd) exits instead of flooding
the log.

M2: the password was read with getchar() after the choice was read with std::cin, which under
sync_with_stdio(false) had already buffered the piped input, so a password piped with the choice
was never seen. On Linux and macOS the password is now read from std::cin. The echo and the line
editing are off for the whole read on a terminal, and the prompt is printed after that, so nothing
typed after it is echoed. The end of the choice's line is skipped. Windows keeps its console read.

L2: writeKeyFile removes whatever has the .tmp name and creates it new (O_EXCL; CREATE_NEW on
Windows): a stale file is not reused, a link not followed, a FIFO not waited on.

L5: decrypt() can report a failed derivation (no memory), and the prompt then says that libsodium
needs about 1 GB instead of "Incorrect password", and does not ask again.

Tests: the end of input cancels (several inputs); a choice and a password piped at once open
the key (not on Windows); a failed derivation is told apart from a wrong password.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- L1: stop every node that uses the key first, an official one or one on another machine too.
- L3: on Windows, type the password in a console, and the files keep the folder's permissions.
- L5: opening the key needs about 1 GB free, so CREDITS_MEMORY must be at least about 1.2g.
- L6: with an encrypted key the container keeps restarting until it is stopped.
- The Docker README snippet saves the keys the container made, and shows the piped form.
- The entrypoint test says what its stub checks, and points to the unit tests for the node's own
  reading of the input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@EnzinoBB
EnzinoBB merged commit ad5bd22 into master Nov 7, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant